Creates a new pixel pattern. Generally, however, your application should create a pixel pattern in a 'ppat' resource.

PixPatHandle NewPixPat ();

function result

A handle to the new PixPat structure created by the NewPixPat function.

DISCUSSION

This function calls the NewPixMap function to allocate the pattern’s PixMap structure and initializes it to the same settings as the pixel map of the current GDevice structure. NewPixPat also sets the pat1Data field of the new PixPat structure to a 50 percent gray pattern. NewPixPat allocates new handles for the PixPat structure’s data, expanded data, expanded map, and color table but does not initialize them; instead, your application must initialize them.

Set the rowBytes, bounds, and pixelSize fields of the pattern’s PixMap structure to the dimensions of the desired pattern. The rowBytes value should be equal to

(width of bounds) x pixelSize/8

The rowBytes value need not be even. The width and height of the bounds must be a power of 2. Each scan line of the pattern must be at least 1 byte in length—that is, ([width of bounds] x pixelSize) must be at least 8.

Your application can explicitly specify the color corresponding to each pixel value with a color table. The color table for the pattern must be placed in the pmTable field in the pattern’s PixMap structure.

Including the PixPat structure itself, NewPixPat allocates a total of five handles. The sizes of the handles to the PixPat and PixMap structures are the sizes of their respective data structures. The other three handles are initially small in size. Once the pattern is drawn, the size of the expanded data is proportional to the size of the pattern data, but adjusted to the depth of the screen. The color table size is the size of the structure plus 8 bytes times the number of colors in the table.

When you are finished using the pixel pattern, use the DisposePixPat function to make the memory used by the pixel pattern available again.

SPECIAL CONSIDERATIONS

The NewPixPat function may move or purge memory blocks in the application heap; do not call this function at interrupt time.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.

© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)